This document explains how to create standalone Macintosh applications using MacOberon. As an example, SampleApp.Mod, a small text editor is included, to show how simple it is to write a Macintosh application. Besides that, the Oberon compiler is a very fast and efficient 32-bit compiler, that produces very dense code, and because of this, programs written by MacOberon are running faster and are smaller than similar programs developed using other programming environments.
Introduction
The Oberon language and the MacOberon compiler are very fast and efficient. So why not use it to develop standard Macintosh applications? In fact, MacOberon can be used to develop such applications without any major limitation. The biggest problem is to implement all Macintosh routines, Types and Constants. In the initial release, we ported only the most important routines and types, and only a few constants. We also followed a new approach, by grouping the data as the new Inside Mac Series does. However, by the time this project finished, not all new Inside Mac books were available, so some data may be at the wrong place, missing or even obsolete.
When porting old Pascal programs to MacOberon, the most expensive changes are to fix the toolbox routine names by adding the right Toolbox module name, for example LineTo becomes MacImaging.LineTo. Most data types and constants can be used without changes, however there are some limitations. See below for more details about this.
The Macintosh Toolbox
Using the Macintosh Toolbox files within MacOberon is a bit different from other programming environments like MPW or Think Pascal/C. Most of all, the data is structured like the new Inside Mac books (from now on IM). There are quite a lot of toolbox calls that changed their spelling in the new IMs, for example the routine that extracts a menu text was called GetItem and spells now GetMenuItemText. In most cases, we use the old spelling, in some special cases both spellings are implemented. (For example DisposPtr and DisposePtr )
However even more important are the changes for register-based toolbox traps. Most of the memory manager routines and some of the file manager routines are register-based. Therefore, you won't be able to use these routines in a common way. You have to push your variables into the registers and read the results afterwards from the registers. When using the IM just use the assembly-language information that always follows the description.
Example :
MPW Pascal : MacOberon :
myPtr:=NewPtr(theSize); SYSTEM.PUTREG(0,theSize);
ME.NewPtr;
SYSTEM.GETREG(8,myPtr);
At first sight, the Oberon version looks very clumsy, but when looking at the produced assembler code, it is obvious, that using MacOberon saves you many instructions when heavily using register-based traps!
Assembler code produced:
CLR.L -(SP) MOVE.L theSize,D0
MOVE.L theSize,-(SP) _NewPtr
JSR xy MOVE.L A0,@myPtr
MOVE.L (SP)+,@myPtr
xy:
MOVEA.L (SP)+,A1
MOVE.L (SP)+,D0
_NewPtr
MOVE.L A0,(SP)
JMP (A1)
Another major difference is how these external Macintosh datatypes and routines can be used. When using MPW Pascal, you only have to import the toolbox files by writing USES <x ,y ,z > and you could use all types and routines like described in the IM. In MacOberon, you also have to import the toolbox files, however you have to precede all types and routines by their module name. It is very convenient to use the alias import feature of Oberon the abbreviate the names of the toolbox modules.
Here are all toolbox files, and their standard abbreviation:
However these toolbox files are not complete, for example, only a very small amount of the constants have been declared. Therefore it will be necessary to add your own data to these files, or even better, create a new toolbox file containing your additions, so you won't need to update all files when new versions of MacOberon are released.
You absolutly need the corresponding Inside Macintosh volumes when adding new routines, types or constanst. It's also helpful if you can get hold of some Interface files of other development platforms. These files are containing all datatypes and constants, and most routines.
When implementing a new routine, just copy the hex code from the interface file. Don't forget the minus right after the PROCEDURE keyword, this tells the compiler to use the inline hex code instead of a procedure body..
Example :
Trap only :
PROCEDURE- PaintRect*(r:Rect)
0A8H,0A2H;
Trap with routine selector :
PROCEDURE- CTabChanged*(port:GrafPtr)
020H,03CH,000H,004H,000H,007H,0ABH,01DH;
There are also some routines described in IM, that are not implemented as traps or traps with routine selectors. These are declared as [NOT IN ROM]. There is currently no official way to use these routines. Either you implement the functionality by yourself, or you disassemble the Interface library from another programming environment, like Interface.o from MPW.
While implementing the toolbox files, simplifications were made to some datatypes. For example most of the types that are aliases to other simple types were left out.
These are for example:
OSErr = INTEGER (also QDError)
Fixed = LONGINT
Size = LONGINT
SignedByte = SHORTINT
In some special cases, we also use LONGINT instead of ME.Ptr to ease the use of the address.
The OSType in IM is declared as ARRAY [0..3] OF CHAR, however, this is nothing else than a LONGINT, so when using OSTypes you can pass a LONGINT, for example 'TEXT' = 54455854H. Two characters stand for the hex representation of the ASCII value of that character.
Another important difference is the byte-length of a character. Macintosh toolbox routines always use two bytes for a CHAR instead of one when using MacOberon. Therefore all toolbox routines using CHARs declare their CHARs as INTEGERs. Just pass ORD(myChar) to such routines where myChar is of Oberontype CHAR. Also remember that the function CHR() also returns a singlebyte CHAR type.
If you want to implement Macintosh datatypes using Ptrs or Handles always follow this scheme :
myDesc* = RECORD ... END;
myPtr* = POINTER- TO myDesc;
myHandle* = POINTER- TO RECORD p*:myPtr END;
The minus after POINTER hides this pointer from garbage collection. Therefore you also have to allocate and deallocate these pointers using NewPtr/DisposePtr, and won't be able to use the Oberon NEW procedure or the garbage collector for these pointers. When dereferencing the handle, just use myHandle.p.<myEntry>.
AppLinker
Using the Applinker is quite simple. There are, however, some rules you have to observe. Because you are using the MacOberon Compiler, the applications produced also need at least an 68020 processor. And if you are using REAL or LONGREAL within your application, FPU code is produced, so you have to check for the presence of an FPU by yourself. The check for an 68020 processor will be made by the bootloader, each time when starting the created application.
If you want to use Oberon memory allocation and garbage collection, you also have to be sure, that the application gets at least a 1MB memory partition for proper operation.
Usage of the AppLinker:
AppLinker.Link SampleApp [Creator]
To link an application, you have to provide the module name of your main module. If you specify a creator, the bundle bit will also be set.
To launch an application within MacOberon, you can use :
AppLinker.Launch SampleApp
If there exists a file named SampleApp.res, then all resources from this file are copied to your application. For proper operation you have to include at least a SIZE resource id=-1 with the following flags set to one:
accept suspend/resume, activate on FG switch and can background
If this resource is not provided, some malfunction may occur when switching between your and other applications.
The AppLinker also adds two code resources (id 0 and 1) containing the bootloader and two ALRT/DITL combinations (id 32766 / 32767) for the error messages and the trap handler. The object code is stored within the data fork of the application.
Oberon Features
The SYSTEM module contains some very useful procedures, some of them are even required to develop Macintosh applications. Most of these procedures are translated into single instructions assembler code. Check the documentation of Oberon for more information about all SYSTEM procedures.
The most important procedures for Macintosh applications are:
SYSTEM.PUTREG(n,x) : Register n := x
SYSTEM.GETREG(n,v) : v := Register n
IF v is of a real type and 0<=n<=7, then floating point registers are used. Otherwise, 0<=n<=7 stands for dataregisters D0-D7, 8<=n<=15 for address registers A0-A7.
It is possible to use Garbage Collection and Run-Time type tests within your Macintosh applications. However, you have to import the module Runtime, and call the GC by yourself.
Ed.Open Runtime.Mod
Examples
There are two examples containing Macintosh toolbox routines. The first one is a small standalone text editor using the build-in Macintosh TextEdit, that can be used as a framework for other applications.
Ed.Open SampleApp.Mod
The second one is an example of using the Oberon System and the Macintosh Interface together. It has only one command, Import, that uses a Macintosh file selector box to choose a plain text file and then opens a simple edit viewer, that contains the text. For example, you can use this command to import text files from other directories into MacOberon.
Ed.Open MacEd.Mod ***Does not apply to MacOberonLite**
Tips & Hints
What's following now is a list of some usful hints, not so obvious to a novice user:
- Use the brower '+' option if you are not sure how your datatypes are allocated. This is very useful if you are implementing new Toolbox datatypes. You will be given the offsets of the record entries and therefore you can calculate the size of these entries. See the Brower.Tool for more information about the Browser. ***Does not apply to MacOberonLite***
- For string conversion between Oberon strings (null terminated) and Macintosh Pascal strings, you can use SetStr255 and GetStr255 from the MacToolbox module.
- When using CASE constructs, use the ELSE path for unwanted results. Otherwise traps may occur.
- When getting system error id=28 increase the memory partition of your program.
- If you are using REAL or LONGREAL operations, please don't forget to check for the presence of an FPU processor, otherwise your program just crashes on machines without an FPU (or an FPU emulator).
Further Reading
- Inside Macintosh Volume I, Chapter 4 (Assembly Language)
- Inside Macintosh Toolbox Essentials (for SampleApp )
